stacked on #944

PR: Public API for Custom Operators with Factory Helpers

Summary

This PR adds a clean public API (defineOperator, defineAggregate) for users to create custom operators and aggregates, along with factory helpers that reduce boilerplate for common patterns.

Changes

New Files

• define.ts - Public API for defineOperator and defineAggregate
• factories.ts - Factory helpers: comparison(), transform(), numeric(), pattern(), booleanOp()

Refactored Built-in Operators

All built-in operators now use the new factory helpers, significantly reducing code duplication:

• Comparison operators (eq, gt, gte, lt, lte) - Use comparison() helper
• Boolean operators (and, or) - Use booleanOp() helper
• Numeric operators (add, subtract, multiply, divide) - Use numeric() helper
• String operators (upper, lower) - Use transform() helper
• Pattern operators (like, ilike) - Use pattern() helper
• Simple operators (isNull, isUndefined, not) - Use defineOperator directly

Tree-Shaking Improvements

• Added /*#__PURE__*/ annotations to all factory calls for better tree-shaking
• Each operator remains in its own file for module-level tree-shaking

New Exports

// Public API
export { defineOperator, defineAggregate } from './define.js'

// Factory helpers for custom operators
export { comparison, transform, numeric, pattern, booleanOp, isUnknown } from './factories.js'

// Types
export type {
  OperatorConfig,
  AggregateDefinition,
  TypedCompiledExpression,
  CompiledArgsFor,
  TypedEvaluatorFactory,
  ExpressionArg,
  ExpressionArgs,
} from './define.js'

Usage Examples

Custom Operator with Factory Helper

import { defineOperator, comparison } from '@tanstack/db'

const notEquals = defineOperator<boolean, [a: unknown, b: unknown]>({
  name: 'notEquals',
  compile: comparison((a, b) => a !== b),
})

Custom Operator with Inline Compile Function

import { defineOperator, isUnknown } from '@tanstack/db'

const between = defineOperator<boolean, [value: number, min: number, max: number]>({
  name: 'between',
  compile: ([value, min, max]) => (data) => {
    const v = value(data)
    if (isUnknown(v)) return null
    return v >= min(data) && v <= max(data)
  }
})

// Use in queries
query.where(({ user }) => between(user.age, 18, 65))

Custom Aggregate

import { defineAggregate } from '@tanstack/db'

const product = defineAggregate<number, number>({
  name: 'product',
  factory: (valueExtractor) => ({
    preMap: valueExtractor,
    reduce: (values) => {
      let result = 1
      for (const [value, mult] of values) {
        for (let i = 0; i < mult; i++) result *= value
      }
      return result
    }
  }),
  valueTransform: 'numeric'
})

API Design Notes

• compile property: Named to reflect the two-phase execution - called once during query compilation to create the per-row evaluator
• Named tuples: TArgs supports named tuples like [value: number, min: number] for better IDE experience
• Factory helpers: Return TypedEvaluatorFactory for type safety while remaining compatible with the internal EvaluatorFactory

Tests

• Added comprehensive runtime tests in custom-operators.test.ts and custom-aggregates.test.ts
• Added type-level tests in custom-operators.test-d.ts and custom-aggregates.test-d.ts
• All 1905 tests pass